Document use of filter columns in pickers #11218

rcorre · 2024-07-18T00:50:44Z

Filtering on columns was implemented in #9647.
The only documentation I could find on this feature
was the PR itself, and the video demo used a different syntax.

Filtering on columns was implemented in helix-editor#9647. The only documentation I could find on this feature was the PR itself, and the video demo used a different syntax.

kirawi · 2024-07-18T02:27:12Z

You can also do multiple filters via syntax like %p:"FILTER_1 FILTER_2 ... FILTER_N" The trailing " is optional if nothing else follows.

rcorre · 2024-07-18T10:24:11Z

Thanks @kirawi! From my testing, it's not %column:"a b", but %column a b

kirawi · 2024-07-18T13:17:18Z

Hmm, you're right. I was running a build of an older version of the picker PR and it seems to have changed.

philipgiuliani · 2024-07-18T13:53:47Z

book/src/keymap.md

+In pickers, you can filter specific columns by prefixing the column name with `%`.
+All words after a `%<column>` term are treated as filters for that column.
+The base filter is a regex, while column filters are a space-separated of literals.
+For example, in the file picker, `init %path api .proto` searches for files containing


Instead of in the file picker it should probably be in the global search picker, right? As you cannot search for file contents in the file picker.

book/src/keymap.md

david-crespo · 2024-07-18T14:44:05Z

Great wording, very helpful and clear. Thank you!

the-mikedavis

This is a good start but I think we may want a larger section to talk about pickers now. We could add a page under the Usage section like we have for textobjects for example and include some gifs

the-mikedavis · 2024-07-18T15:02:35Z

book/src/keymap.md

@@ -452,6 +452,13 @@ Keys to use within picker. Remapping currently not supported.
 | `Ctrl-t`                     | Toggle preview                                             |
 | `Escape`, `Ctrl-c`           | Close picker                                               |

+In pickers, you can filter specific columns by prefixing the column name with `%`.
+All words after a `%<column>` term are treated as filters for that column.
+The base filter is a regex, while column filters are a space-separated of literals.


Actually columns use fuzzy filtering. There are two exceptions: the default columns for global_search and the LSP workspace_symbol_picker. global_search's default column is a regex and workspace_symbol_picker's is sent to the language server so it can do its own filtering.

book/src/keymap.md

Co-authored-by: Michael Davis <[email protected]>

rcorre · 2024-07-18T23:28:37Z

I think I discovered by accident that ! negates a term. Are there any other hidden features I should know about? 😆

pascalkuthe · 2024-07-19T00:02:27Z

That's not new and been implememted for a long time. That is standard fzf syntax.

rcorre · 2024-07-19T11:43:01Z

I've moved picker docs to their own section.
I'm happy to record some gifs/asciinema, but I'm unclear on how to use them.
It looks like the gifs currently in the docs are links to user-images.githubusercontent.com.
Should I just post gifs in this PR, then link them in the book? Will those links stay alive indefinitely?

book/src/pickers.md

rcorre · 2024-07-19T11:58:40Z

book/src/pickers.md

+
+Most pickers perform fuzzy matching using [fzf syntax](https://github.com/junegunn/fzf?tab=readme-ov-file#search-syntax). Two exceptions are the global search picker, which uses regex, and the workspace symbol picker, which passes search terms to the LSP.
+
+If a picker shows multiple columns, you may apply the filter to a specific column by prefixing the column name with `%`. Column names can be shortened to any prefix, so `%p`, `%pa` or `%pat` all mean the same as `%path`. For example, `helix %p .toml$ !lang` searches for the term "helix" within files with paths ending in ".toml" but not including "lang".


Actually, I thought .toml$ was working, but it isn't. It seems that the line number is considered part of the path, e.g. .toml:7$ works. Is that intentional?

Right the line number is considered part of the path column for the sake of fuzzy matching. So instead of adding $ at the end of a path you can add a : instead, e.g. %p file.rs:

book/src/pickers.md

nick42d

Was in this space recently with #11245 and so added my 2c. Looks good, minor feedback only.

nick42d · 2024-07-20T05:35:14Z

book/src/pickers.md

+
+### Filtering Picker Results
+
+Most pickers perform fuzzy matching using [fzf syntax](https://github.com/junegunn/fzf?tab=readme-ov-file#search-syntax). Two exceptions are the global search picker, which uses regex, and the workspace symbol picker, which passes search terms to the LSP.


There's an exception to the fzf syntax - the OR syntax is not implemented yet per discussion on #11245

Is there an issue specifically for OR support? I couldn't find it.

Not that I'm aware of either outside of #11245.

book/src/pickers.md

Co-authored-by: Michael Davis <[email protected]>

the-mikedavis

just a minor edit, otherwise this is looking good

book/src/pickers.md

Co-authored-by: Michael Davis <[email protected]>

dvic · 2024-07-25T09:06:45Z

Just to double check:

For example, a query of helix %p .toml$ !lang in the global search picker searches for the term "helix" within files with paths ending in ".toml" but not including "lang".

For me this example doesn't work, because the line numbers in the format of :123 are appended to the path.

So something %path .exs$ doesn't work but something %path .exs:439$ does. Is this expected? Or should the path matching be updated to exclude the line numbers part?

rcorre · 2024-07-25T10:44:40Z

Argh, you're correct @dvic. I meant to correct that but forgot: #11218 (comment).

should the path matching be updated to exclude the line numbers part

Personally I think that's the better approach here, but I'm not sure how difficult that is (I can't imagine ever wanting to filter on line number.

dvic · 2024-07-25T10:49:20Z

Argh, you're correct @dvic. I meant to correct that but forgot: #11218 (comment).

should the path matching be updated to exclude the line numbers part

Personally I think that's the better approach here, but I'm not sure how difficult that is (I can't imagine ever wanting to filter on line number.

Ahhh I missed that conversation. @the-mikedavis What is your opinion on this? I also think it's not really useful to include the line number in the matching but I don't know how big of an effort it is to exclude this.

the-mikedavis · 2024-07-25T13:35:53Z

Oh whoops I missed that in review. For now we should update the docs to say : instead of $. @pascalkuthe and I talked about line numbers and thought it might better belong in the preview instead (so an absolute line number gutter in the preview pane) rather than the path search text. Then $ would apply as currently documented

As discussed in helix-editor#11218 (comment)

* Document use of filter columns in pickers. Filtering on columns was implemented in helix-editor#9647. The only documentation I could find on this feature was the PR itself, and the video demo used a different syntax. * Note that column filters are space-separated. * Note that picker filters can be abbreviated. * Specify correct picker in docs. * Clarify picker filter prefix shortenting. Co-authored-by: Michael Davis <[email protected]> * Move picker docs to their own section. * Update book/src/pickers.md Co-authored-by: Michael Davis <[email protected]> * Improve docs on picker registers, keybinds, and syntax. * Clarify wording around picker queries. Co-authored-by: Michael Davis <[email protected]> --------- Co-authored-by: Ryan Roden-Corrent <[email protected]> Co-authored-by: Michael Davis <[email protected]>

Document use of filter columns in pickers.

ea2cb65

Filtering on columns was implemented in helix-editor#9647. The only documentation I could find on this feature was the PR itself, and the video demo used a different syntax.

Note that column filters are space-separated.

86e6e6d

Note that picker filters can be abbreviated.

2aa831e

philipgiuliani reviewed Jul 18, 2024

View reviewed changes

rcorre commented Jul 18, 2024

View reviewed changes

book/src/keymap.md Outdated Show resolved Hide resolved

Specify correct picker in docs.

033d5fa

the-mikedavis reviewed Jul 18, 2024

View reviewed changes

the-mikedavis added the A-documentation Area: Documentation improvements label Jul 18, 2024

Clarify picker filter prefix shortenting.

fe337b4

Co-authored-by: Michael Davis <[email protected]>

Move picker docs to their own section.

85066a7

rcorre commented Jul 19, 2024

View reviewed changes

book/src/pickers.md Outdated Show resolved Hide resolved

rcorre commented Jul 19, 2024

View reviewed changes

the-mikedavis reviewed Jul 19, 2024

View reviewed changes

book/src/pickers.md Outdated Show resolved Hide resolved

This was referenced Jul 19, 2024

Pickers "v2" #9647

Merged

Global search v2 cannot filter by path #11240

Closed

the-mikedavis linked an issue Jul 19, 2024 that may be closed by this pull request

Picker V2 are lacking user-facing docs on how to use them #11181

Closed

nick42d mentioned this pull request Jul 20, 2024

Feature request: Toggle minimum diagnostic severity for diagnostic picker #11245

Open

nick42d reviewed Jul 20, 2024

View reviewed changes

rcorre and others added 2 commits July 20, 2024 07:42

Update book/src/pickers.md

8aa5f3f

Co-authored-by: Michael Davis <[email protected]>

Improve docs on picker registers, keybinds, and syntax.

9c020e9

nick42d approved these changes Jul 20, 2024

View reviewed changes

the-mikedavis reviewed Jul 23, 2024

View reviewed changes

book/src/pickers.md Outdated Show resolved Hide resolved

Clarify wording around picker queries.

64d4c8b

Co-authored-by: Michael Davis <[email protected]>

the-mikedavis approved these changes Jul 23, 2024

View reviewed changes

the-mikedavis changed the title ~~Document use of filter columns in pickers.~~ Document use of filter columns in pickers Jul 23, 2024

pascalkuthe approved these changes Jul 24, 2024

View reviewed changes

pascalkuthe merged commit 5d3f05c into helix-editor:master Jul 24, 2024
6 checks passed

rcorre deleted the doc-filter-picker branch July 25, 2024 10:44

dvic added a commit to dvic/helix that referenced this pull request Jul 25, 2024

Fix example query in pickers.md

1f2b739

As discussed in helix-editor#11218 (comment)

dvic mentioned this pull request Jul 25, 2024

Fix example query in pickers.md #11322

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document use of filter columns in pickers #11218

Document use of filter columns in pickers #11218

rcorre commented Jul 18, 2024

kirawi commented Jul 18, 2024 •

edited

Loading

rcorre commented Jul 18, 2024

kirawi commented Jul 18, 2024

philipgiuliani Jul 18, 2024

david-crespo commented Jul 18, 2024

the-mikedavis left a comment

the-mikedavis Jul 18, 2024

rcorre commented Jul 18, 2024

pascalkuthe commented Jul 19, 2024

rcorre commented Jul 19, 2024

rcorre Jul 19, 2024

the-mikedavis Jul 19, 2024

nick42d left a comment

nick42d Jul 20, 2024

rcorre Jul 20, 2024

nick42d Jul 20, 2024

the-mikedavis left a comment

dvic commented Jul 25, 2024 •

edited

Loading

rcorre commented Jul 25, 2024

dvic commented Jul 25, 2024

the-mikedavis commented Jul 25, 2024


		Most pickers perform fuzzy matching using [fzf syntax](https://github.com/junegunn/fzf?tab=readme-ov-file#search-syntax). Two exceptions are the global search picker, which uses regex, and the workspace symbol picker, which passes search terms to the LSP.

		If a picker shows multiple columns, you may apply the filter to a specific column by prefixing the column name with `%`. Column names can be shortened to any prefix, so `%p`, `%pa` or `%pat` all mean the same as `%path`. For example, `helix %p .toml$ !lang` searches for the term "helix" within files with paths ending in ".toml" but not including "lang".


		### Filtering Picker Results

		Most pickers perform fuzzy matching using [fzf syntax](https://github.com/junegunn/fzf?tab=readme-ov-file#search-syntax). Two exceptions are the global search picker, which uses regex, and the workspace symbol picker, which passes search terms to the LSP.

Document use of filter columns in pickers #11218

Document use of filter columns in pickers #11218

Conversation

rcorre commented Jul 18, 2024

kirawi commented Jul 18, 2024 • edited Loading

rcorre commented Jul 18, 2024

kirawi commented Jul 18, 2024

philipgiuliani Jul 18, 2024

Choose a reason for hiding this comment

david-crespo commented Jul 18, 2024

the-mikedavis left a comment

Choose a reason for hiding this comment

the-mikedavis Jul 18, 2024

Choose a reason for hiding this comment

rcorre commented Jul 18, 2024

pascalkuthe commented Jul 19, 2024

rcorre commented Jul 19, 2024

rcorre Jul 19, 2024

Choose a reason for hiding this comment

the-mikedavis Jul 19, 2024

Choose a reason for hiding this comment

nick42d left a comment

Choose a reason for hiding this comment

nick42d Jul 20, 2024

Choose a reason for hiding this comment

rcorre Jul 20, 2024

Choose a reason for hiding this comment

nick42d Jul 20, 2024

Choose a reason for hiding this comment

the-mikedavis left a comment

Choose a reason for hiding this comment

dvic commented Jul 25, 2024 • edited Loading

rcorre commented Jul 25, 2024

dvic commented Jul 25, 2024

the-mikedavis commented Jul 25, 2024

kirawi commented Jul 18, 2024 •

edited

Loading

dvic commented Jul 25, 2024 •

edited

Loading